<!--
  ~ SPDX-License-Identifier: Apache-2.0
  ~ Copyright Red Hat Inc. and Hibernate Authors
  -->
<body>

<h2>Hibernate ORM Javadocs</h2>

<p>
    Hibernate is a library for object/relation mapping (ORM). It provides:
</p>
<ul>
    <li>
        a <em>native API</em> centered around {@link org.hibernate.SessionFactory},
        {@link org.hibernate.Session}, and {@link org.hibernate.StatelessSession},
    </li>
    <li>
        an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA),
        where the equivalent central interfaces are {@link jakarta.persistence.EntityManagerFactory}
        and {@link jakarta.persistence.EntityManager},
    </li>
    <li>
        a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined
        by JPA, and which may be used with either API, and
    </li>
    <li>
        <em>compile-time tooling</em> for writing more type-safe code.
    </li>
</ul>

<h3>Native API</h3>

<p>
    Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications
    using the native API will often make use of the following interfaces:
</p>
<ul>
    <li>{@link org.hibernate.jpa.HibernatePersistenceConfiguration} or
        {@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
    <li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
    <li>{@link org.hibernate.Transaction} to control local transactions,</li>
    <li>{@link org.hibernate.query.SelectionQuery} and {@link org.hibernate.query.MutationQuery} to
        execute HQL queries,</li>
    <li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
    <li>{@link org.hibernate.query.specification.SelectionSpecification} and
        {@link org.hibernate.query.specification.MutationSpecification} for working with dynamic
        {@linkplain org.hibernate.query.restriction.Restriction restrictions} and
        {@linkplain org.hibernate.query.Order ordering},</li>
    <li>{@link org.hibernate.Filter} to manage filters,</li>
    <li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
        and</li>
    <li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>
</ul>

<h3>JPA</h3>

<p>
    The JPA interfaces are defined by the JPA specification. For details see the latest
    <a href="https://jakarta.ee/specifications/persistence/">specification</a> along with the
    <a href="https://jakarta.ee/specifications/persistence/3.2/apidocs/">API documentation</a>
    for the package {@link jakarta.persistence}.
</p>
<p>
    Along with {@link jakarta.persistence.EntityManagerFactory} and
    {@link jakarta.persistence.EntityManager}, programs based on the standard JPA API often use:
</p>
<ul>
    <li>{@link jakarta.persistence.Persistence} and {@link jakarta.persistence.PersistenceConfiguration}
        to bootstrap Hibernate via JPA,</li>
    <li>{@link jakarta.persistence.TypedQuery} to execute queries,</li>
    <li>{@link jakarta.persistence.EntityGraph} to control the boundaries of fetched data,</li>
    <li>{@link jakarta.persistence.EntityTransaction} to control local transactions,</li>
    <li>{@link jakarta.persistence.Cache} to manage the second-level cache,</li>
    <li>{@link jakarta.persistence.SchemaManager} to execute DDL in tests,</li>
    <li>{@link jakarta.persistence.criteria.CriteriaBuilder} to construct criteria queries,</li>
    <li>{@link jakarta.persistence.metamodel.Metamodel} to implement generic code which makes use of
        persistent entity classes in a reflective fashion, and</li>
    <li>{@link jakarta.persistence.criteria.CriteriaBuilder} to build JPA criteria queries.</li>
</ul>
<p>
    Note that since Hibernate 5.2, the native API extends the JPA API rather than wrapping it.
    For example, <code>SessionFactory</code> extends <code>EntityManagerFactory</code>, and
    <code>Session</code> extends <code>EntityManager</code>.
</p>
<p>
    It's always possible to fall back from JPA interfaces to native APIs, by calling
    {@link jakarta.persistence.EntityManager#unwrap entityManager.unwrap(Session.class)},
    {@link jakarta.persistence.EntityManagerFactory#unwrap entityManagerFactory.unwrap(SessionFactory.class)},
    or {@link jakarta.persistence.Query#unwrap query.unwrap(Query.class)}. In certain cases
    it's also possible to access native functionality by passing a
    {@linkplain org.hibernate.jpa.SpecHints JPA-defined} or
    {@linkplain org.hibernate.jpa.HibernateHints Hibernate-defined} hint, at the cost of a
    loss of type-safety.
</p>
<p>
    These packages define additional extensions to the JPA APIs:
</p>
<ul>
    <li>{@link org.hibernate.query.criteria} packages extensions to {@link jakarta.persistence.criteria}, and</li>
    <li>{@link org.hibernate.metamodel.model.domain} packages extensions to {@link jakarta.persistence.metamodel}.</li>
</ul>

<h3>Mapping annotations</h3>

<p>
    The mapping annotations defined by the JPA specification provide a foundation for expressing
    object/relational mappings in Hibernate and other JPA implementations.
</p>
<p>
    The annotations in the package {@link org.hibernate.annotations} extend this foundation and
    accommodate more specialized requirements. These annotation are not tied to the native API,
    and may be used in conjunction with the JPA API.
</p>
<p>
    The full power of Hibernate can only be unlocked via judicious use of these extra annotations.
</p>

<h3>XML-based mappings</h3>

Annotation-based mappings are the best choice for most users, but Hibernate offers XML-based
mappings as an alternative.

<ul>
    <li>
        The JPA-standard XML schema is
        <a href="https://jakarta.ee/xml/ns/persistence/orm/orm_3_0.xsd">orm_3_0.xsd</a>.
    </li>
    <li>
        Hibernate extends this schema with some additional mapping elements. The extended schema is
        <a href="https://hibernate.org/xsd/orm/mapping/mapping-3.1.0.xsd">mapping-3.1.0.xsd</a>.
    </li>
    <li>
        Prior to the existence of JPA, Hibernate had its own format for XML-based mappings,
        which still works, though it has not been improved in a long time. The DTD is
        <a href="https://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">hibernate-mapping-3.0.dtd</a>
    </li>
</ul>

<h3>Bootstrapping Hibernate</h3>

<p>
    There are four basic ways to obtain an instance of Hibernate:
</p>
<ul>
    <li>
        as a JPA <em>persistence provider</em>, by using
        {@link jakarta.persistence.Persistence#createEntityManagerFactory},
    </li>
    <li>
        by using the "simplified" {@link org.hibernate.cfg.Configuration} API,
    </li>
    <li>
        for those who enjoy dirty hands, by using the APIs in {@link org.hibernate.boot}, or
    </li>
    <li>
        in a <em>container environment</em> like
        <a href="https://www.wildfly.org">WildFly</a> or <a href="https://quarkus.io">Quarkus</a>,
        by letting the container take care of the bootstrap process and of injecting the
        {@code EntityManagerFactory} or {@code SessionFactory}.
    </li>
</ul>
<p>
    All major Java application servers and microservice frameworks come with built-in support for
    Hibernate. Such container environments also typically feature facilities to automatically
    manage the lifecycle of a {@code EntityManager} or {@code Session} and its association with
    container-managed transactions.
</p>
<p>
    Example configuration files for JPA and native usage may be found {@linkplain org.hibernate.cfg
    here}. A comprehensive list of configuration properties understood by Hibernate may be found in
    the class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
    to use a tiny handful of them.
</p>

<h3>Annotations driving compile-time tooling</h3>

<p>
    The annotations defined by {@link org.hibernate.annotations.processing} instruct the Metamodel
    Generator to {@linkplain org.hibernate.annotations.processing.CheckHQL validate HQL at compile
    time}, and to automatically generate the implementation of
    {@linkplain org.hibernate.annotations.processing.Find finder methods} and
    {@linkplain org.hibernate.annotations.processing.HQL query methods}.
<p>

<h3>Popular extension points</h3>

<p>
    Hibernate offers an enormous wealth of extension points for customizing almost any aspect of
    its implementation. Most of these extension points are far too technical to be of interest to
    the typical application developer.
</p>
<p>
    However, the following extension points are of quite general interest:
</p>
<ul>
    <li>
        {@link org.hibernate.boot.model.naming} allows the quantity of repetitive O/R mapping
        metadata to be minimized via the use of naming strategies,
    </li>
    <li>
        {@link org.hibernate.type.descriptor.jdbc} and {@link org.hibernate.type.descriptor.java}
        contain the built-in {@code JdbcType}s and {@code JavaType}s for "compositional" basic
        attribute type mappings,
    </li>
    <li>
        {@link org.hibernate.usertype} defines support for user-defined custom attribute types,
    </li>
    <li>
        {@link org.hibernate.generator} defines support for generated attribute values,
    </li>
    <li>
        {@link org.hibernate.context.spi} defines support for context-bound "current" sessions
        and contextual multi-tenancy, and
    </li>
    <li>
        {@link org.hibernate.binder} allows for user-defined mapping annotations.
    </li>
</ul>
<p>
    More advanced extension points include:
</p>
<ul>
    <li>
        {@link org.hibernate.dialect} provides a framework for modelling dialects of SQL,
    </li>
    <li>
        {@link org.hibernate.cache.spi} defines an SPI for integrating with second-level cache
        providers,
    </li>
    <li>
        {@link org.hibernate.engine.jdbc.connections.spi} defines an SPI for integrating with
        JDBC connection pools.
    </li>
</ul>
<p>
    Finally, Hibernate ORM Core is itself a framework for advanced extensions like Hibernate Search,
    Hibernate Reactive, and Envers, which do much more than just implementing a single well-defined
    extension point. The starting points for such extensions are found in the packages
    {@link org.hibernate.integrator.spi} and  {@link org.hibernate.event.spi}.
</p>

<h3>Package categories</h3>

<p>
    The organization of code into packages is based on the following classification:
</p>
<ul>
    <li>
        <strong>API packages</strong> include classes and interfaces which are used directly by
        a typical application. These packages never have <code>spi</code> nor <code>internal</code>
        in their name, and are not under the namespace <code>org.hibernate.testing</code>.
    </li>
    <li>
        <strong>SPI packages</strong> include classes and interfaces which are used by integrators,
        library developers, and framework developers to develop extensions to Hibernate, or to alter
        its behavior in some way. These packages usually have <code>spi</code> in their name.
    </li>
    <li>
        Some classes and interfaces are considered part of the internal implementation of Hibernate.
        This category includes packages with <code>internal</code> in their name, along with any class
        or interface annotated {@link org.hibernate.Internal @Internal}. Clients should avoid depending
        directly on these types.
    </li>
    <li>
        The <code>hibernate-testing</code> module, and the namespace <code>org.hibernate.testing</code>
        contain <strong>testing support</strong> used in the Hibernate test suite.
    </li>
</ul>

<h3>More information</h3>

<p>
    Complete documentation may be found online at
    <a href="http://hibernate.org/orm/documentation">http://hibernate.org/orm/documentation/</a>.
</p>

</body>